Inside Macintosh: Overview /

Chapter 9 - Processes

Handling Suspend and Resume Events

Your application receives suspend and resume events as a result of changes in its processing status. When your application is in the foreground and the Process Manager wants to switch it into the background, the Process Manager sends it a suspend event. This is a signal to your application to prepare to be switched out. Your application isn't actually switched out immediately. Instead, the Process Manager gives your application a chance to handle the suspend event. Your application is switched out at the next event call it makes. Similarly, the application that is about to be switched into the foreground is sent a resume event once it's actually switched. The resume event is a signal to that application that it can resume normal foreground processing.

Upon receiving a suspend event, your application should deactivate the front window, remove the highlighting from any selections, and hide any floating windows. Your application should also convert any private scrap into the global scrap, if necessary. If your application shows a window that displays the Clipboard contents, you should hide this window also, because the user might change the contents of the Clipboard before returning to your application. Your application can also do anything else necessary to get ready for a major switch. Then your application should call WaitNextEvent to relinquish the processor and allow the Operating System to schedule other processes for execution.

Upon receiving a resume event, your application should activate the front window and restore any windows to the state the user left them in at the time of the previous suspend event. For example, your application should show scroll bars, restore any selections that were previously in effect, and show any floating windows. Your application should copy the contents of the Clipboard and convert the data back to its private scrap, if necessary. If your application shows a window that displays the Clipboard contents, you can update the contents of the window after reading in the scrap. Your application can then resume interacting with the user.

Responding to a suspend or resume event usually involves activating or deactivating windows. If you set the acceptSuspendResumeEvents flag and the doesActivateOnFGSwitch flag in your application's 'SIZE' resource, your application is responsible for activating or deactivating its windows when it handles suspend and resume events.

Listing 9-2 defines the routine called by the Venn Diagrammer application to handle operating-system events.

Listing 9-2 Handling operating-system events

PROCEDURE DoOSEvent (myEvent: EventRecord);
   VAR
      myWindow:   WindowPtr;
BEGIN
   CASE BSR(myEvent.message, 24) OF
      mouseMovedMessage: 
         BEGIN
            DoIdle(myEvent);                          {right now, do nothing}
         END;
      suspendResumeMessage: 
         BEGIN
            myWindow := FrontWindow;
            IF (BAnd(myEvent.message, resumeFlag) <> 0) THEN
               DoActivate(myWindow, activeFlag)       {activate window}
            ELSE
               DoActivate(myWindow, 1 - activeFlag);  {deactivate window}
         END;
      OTHERWISE
         ;
   END;
END;

The procedure DoOSEvent is called by the main event loop (Listing 4-4 on page 77) whenever the what field of an event record contains the constant osEvt. You need to inspect the message field of that event record to determine what kind of operating-system event you've received. Table 9-1 shows the information contained in the bits of the message field.

The bits in the message field of an operating-system event record

Bit	Contents
0	0 if a suspend event 1 if a resume event
1	0 if Clipboard conversion is not required 1 if Clipboard conversion is required
2-23	Reserved
24-31	suspendResumeMessage if a suspend or resume event mouseMovedMessage if a mouse-moved event

As you can see, you need to inspect bits 24-31 to determine what kind of operating-system event you've received. Those eight bits contain one of two constants:

CONST 
   suspendResumeMessage    = $01;      {suspend or resume event}
   mouseMovedMessage       = $FA;      {mouse-moved event}

If the event is a suspend or resume event, you then need to examine bit 0 to determine whether that event is a suspend or resume event. (Bits 0 and 1 are meaningful only if bits 24-31 indicate that the event is a suspend or resume event.) You can use the resumeFlag constant to determine whether the event is a suspend or resume event. If the event is a resume event, you can use the convertClipboardFlag constant to determine whether Clipboard conversion from the Clipboard to your application's scrap is required.

CONST
   resumeFlag              = 1;  {resume event}
   convertClipboardFlag    = 2;  {Clipboard conversion required}

The procedure DoOSEvent defined in Listing 9-2 first checks what kind of event it has received. If the event is a mouse-moved event, DoOSEvent ignores the event, treating it like a null event. If the event is a suspend or resume event, DoOSEvent then activates or deactivates the front window, depending on whether the event is a resume or a suspend event.

Note

Because the Venn Diagrammer application doesn't support cutting or pasting, it doesn't need to worry about converting the Clipboard.